---
title: LEDs
---

# LEDs

Controlling strips of programmable LEDs can be done through the `Led` client.

**This client requires to import the `@devicescript/runtime` to get all the functionalities.**

```ts
import { Led } from "@devicescript/core"
// highlight-next-line
import "@devicescript/runtime"

const led = new Led()
```

## Driver

You can start a driver for WS2812 or AP102 using [startLed](./leds/driver).

```ts
import { LedVariant, LedStripLightType } from "@devicescript/core"
import { startLed } from "@devicescript/drivers"
import { pins } from "@dsboard/adafruit_qt_py_c3"
import { spi } from "@devicescript/spi"

// highlight-start
const led = await startLed({
    length: 32,
    variant: LedVariant.Ring,
    hwConfig: {
        type: LedStripLightType.SK9822,
        pinClk: pins.A1_D1,
        pinData: pins.A0_D0,
        spi: spi,
    },
})
// highlight-end
```

## Simulation and long strips (> 64 LEDs)

For short LED strips, 64 LEDs or less, DeviceScript provides full simulation and device twin
for hardware and simulated devices.

For strips longer than 64 LEDs, the simulator device will work but the hardware device twin will
not work anymore. This is a simple limitation that the data overflows the packets used in Jacdac.

## PixelBuffer and show

The `Led` client has a [pixel buffer](/api/runtime/pixelbuffer), a 1D vector of colors,
that can be used to perform color operations, and a `show` function to render the buffer to the hardware.

A typical LED program would then look like this:

```ts
import { LedStripLightType } from "@devicescript/core"
import { startLed } from "@devicescript/drivers"
import { fillSolid } from "@devicescript/runtime"
import { pins } from "@dsboard/adafruit_qt_py_c3"

const led = await startLed({
    length: 32,
    hwConfig: { type: LedStripLightType.WS2812B_GRB, pin: pins.A0_D0 },
})

// retreive pixel buffer from led
const pixels = await led.buffer()
// do operations on pixels, like setting LEDs to green
fillSolid(pixels, 0x00ee00)
// send colors to hardware
await led.show()
```

### showAll

A convenience function `showAll` is provided to set the color of all LEDs.

```ts
import { Led } from "@devicescript/core"
import "@devicescript/runtime"

const led = new Led()
// highlight-next-line
await led.showAll(0x00ee00)
```

## LED Display

You can mount a LED matrix as a [display](./leds/display).
This can be helpful for matrix-shaped LEDs.

```ts
import { pins } from "@dsboard/esp32_c3fh4_rgb"
import { LedStripLightType, LedVariant } from "@devicescript/core"
import { startLed } from "@devicescript/drivers"
import { startLedDisplay } from "@devicescript/runtime"

const led = await startLed({
    length: 25,
    columns: 5,
    variant: LedVariant.Matrix,
    hwConfig: { type: LedStripLightType.WS2812B_GRB, pin: pins.LEDS },
})

// highlight-next-line
const display = await startLedDisplay(led)
```
